home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Libris Britannia 4
/
science library(b).zip
/
science library(b)
/
COMMUNIC
/
H191.ZIP
/
CA29-4.EXE
/
CACMP.DOC
next >
Wrap
Text File
|
1992-11-30
|
21KB
|
880 lines
COM-AND Script Utility
---------------------------------------
COM-AND Script Utility
Script utility for the COM-AND language
---------------------------------------
CACMP ver.1.2 and COM-AND are copyright by 1992 CABER Software.
CACMP and COM-AND are distributed freely and may be copied by
anyone for any number of machines, for purposes of evaluation.
The author offers COM-AND and its accessory programs together
as "shareware". If you USE the program you MUST pay for it.
The complete user license and registration information is to be
found in the file REGISTER.DOC. Limitations on redistribution
of COM-AND are set out in the file VENDOR.DOC. These two files
are included with the COM-AND program release.
CABER Software
R. (Scott) McGinnis
P.O. Box 3607 Mdse Mart
Chicago, IL 60654-0607
GEnie, Delphi: TARTAN
CIS .......... 73147,2665
Internet ..... 73147.2665@compuserve.com
Version 1.2: 921012
COM-AND Script Utility
Table of Contents
-----------------
I. Introduction .............................................. page 1
II. Running CACMP ............................................. page 2
III. CACMP functions ............................................ page 4
A. Syntax check ............................................ page 4
B. Semantic check .......................................... page 5
C. Partial strip ........................................... page 9
D. Full strip .............................................. page 10
E. Preprocessing ........................................... page 11
IV. CACMP and COM-AND .......................................... page 12
V. Program Requirements ....................................... page 13
VI. Program and Author Information ............................ page 14
Version 1.2: 921012
COM-AND Script Utility Page 1
I. Introduction
A. What is COM-AND?
COM-AND for the IBM PC and compatibles is a communications pro-
gram for use by itself, or with several integrated accessory
programs (which themselves may be used independently of COM-AND).
COM-AND provides standard comm program functions: a dialing
directory, macros, disk logging, binary and ASCII file transfers,
... and scripted execution.
B. COM-AND scripts
A script automates certain manual tasks, and allows COM-AND to
run unattended (if the script has been tested (!!!)). A script
is a program written to control COM-AND execution. Scripts
distributed with COM-AND include: LEARN mode (a script that
writes a script), a FILEMGR (perform DOS functions and find
files for transmission), a BBS, a HOST mode, and many more.
Script commands are read by COM-AND from an ASCII file (word
processor files are not usually ASCII files (!)). COM-AND's
internal editor (Alt-Q), programmer's text editors and EDLIN
(included with DOS) may be used to create and modify a script
file.
C. The CACMP program
CACMP is a diagnostic and preprocessor for COM-AND scripts.
CACMP may be used simply to perform syntax and semantic review
of a COM-AND script, or it may be used to preprocess scripts
for COM-AND.
This document discusses the use of CACMP.EXE. COM-AND scripts
and the script language are discussed in the CASCRIPT.DOC
document, distributed with COM-AND.
Version 1.2: 921012
COM-AND Script Utility Page 2
II. Running CACMP
Generally, CACMP is invoked at the DOS prompt with the command:
-----------------------------------------------------------------
"d>" CACMP <options> [<infilename> [<outfilename>]]
Where "d>" is the DOS prompt, and
<options> are [<switch> [<switch> ...]]
-----------------------------------------------------------------
CACMP could be invoked with a command such as:
"d>" CACMP
to simply start CACMP. In this case, CACMP prompts for an input
file and does not write a stripped/preprocessed file. The command:
"d>" CACMP /s
causes CACMP to prompt for both an input AND an output file name
(the input file MUST NOT be the same as the output file). Output
is the input stripped of comments (see below).
CACMP by default deletes an output file (if there is one) when a
syntax error is found. This action may be inhibited with the switch
"/k". In the case:
"d>" CACMP /s/k
the output file is retained (and lines marked as 'syntax errors'
are retained (partially stripped, regardless of preprocessing).
The input file name (and output file name) may be specified in the
run command. For example:
"d>" CACMP /s bbs.src
reads the file BBS.SRC and prompts for an output file name. Input
file names default to the extension ".CMD" if the name given is not
found. The output file, if it exists, is deleted and recreated when
CACMP begins. For this reason, CACMP must not be run with the same
file as INPUT and output.
Version 1.2: 921012
COM-AND Script Utility Page 3
II. Running CACMP (continued)
The following switches are defined for CACMP at run-time:
/1 Partial strip output (see below)
/s Full strip output (see below)
/k Keep output when syntax error is detected
/p Preprocess script (for speed)
The default settings for CACMP are: no output, and delete output if
a syntax error is detected.
All error and diagnostic output by CACMP is directed to the standard
output device. Therefore, the command:
"d>" CACMP >temp script.cmd
records all the diagnostic information in the file TEMP on the cur-
rent subdirectory, for later review.
When CACMP terminates it displays the following summary:
Total input lines:
Total input statements:
Total input comments:
Total input labels:
Total syntax errors:
Total semantic warnings:
If CACMP created an output file, CACMP also reports:
Input file size:
Output file size:
CACMP terminates with a DOS error level of 0 if no syntax errors and
no semantic errors are detected. CACMP terminates with a DOS error
level of 1 if either syntax or semantic errors are reported. [Batch
checks of a group of scripts may be stopped on an error using the
error level returned to DOS.]
Version 1.2: 921012
COM-AND Script Utility Page 4
III. CACMP functions
A. Syntax check
CACMP's first function is to syntactically verify each line of
the input file. Syntax errors are noted as follows:
Line 3: Syntax error
S0 = N0+5(N1+ N2)
^
General parse failure (syntax)
The first line records the line number and the error. The second
line echoes the input line. The third line points to the highest
point the parser reached parsing the line (probably close to the
point at which the error occurs). The fourth line adds any addi-
tional information returned by the parser.
Developer's note: In the fourth line, ANY return except the one
above should be reported to the author. The fourth line properly
may be considered diagnostic to CACMP. For example, 'Stack
overflow' at this point indicates that the parser recursed beyond
its stack - a CACMP problem and not an input problem.
All error and diagnostic information listed by CACMP is directed
to the standard output device. Therefore, the command:
"d>" CACMP >temp script.cmd
records all CACMP diagnostic information in the file TEMP on the
current subdirectory, for later review.
Syntax errors are counted, and the number reported at CACMP ter-
mination. If CACMP is used to strip/preprocess a file and syntax
errors are detected, the output file is deleted (unless /k in
the run command is specified).
Version 1.2: 921012
COM-AND Script Utility Page 5
III. CACMP functions (continued)
B. Semantic check
Beyond syntactic verification of each line, CACMP follows the
input file to verify the structure of the script. Semantic
verification in CACMP consists of:
1. Overlapped domains
The IF, SWITCH, WHILE, FOR and DO statements imply a 'domain'
of execution. The domain of the IF statement extends until
an ENDIF statement (except in compound IF statements, where
a single statement to be executed (when the condition is
true) is carried on the same line). The domain of a SWITCH
statement extends until an ENDSWITCH. Similarly the WHILE,
FOR and DO statements domains extend until their respective
terminators.
Domains may NOT overlap. For example, the following
construction is an overlapped domain:
WHILE N0 LT 5
IF N0 EQ 3
ENDWHILE
GOTO somewhere
ENDIF
ENDWHILE
[In the above case, the ENDWHILE within the IF domain is
superfluous (the WHILE loop domain would terminate on the
GOTO).] CACMP diagnoses this code as:
Line 3: WARNING: Overlapped domain
ENDWHILE
^
....... Current domain is IF starting: 2
The ENDWHILE on line 3 overlaps the IF domain that began
in line 2.
Version 1.2: 921012
COM-AND Script Utility Page 6
III. CACMP functions (continued)
B. Semantic check (continued)
2. Incomplete domain
On completion of processing, domains left open (i.e. with-
out closure) are reported as 'incomplete domains' by CACMP.
For example:
WARNING: Incomplete WHILE domain starting: 1
In this case, a WHILE loop was not properly closed with an
ENDWHILE. The WHILE statement is in line 1.
3. Unreachable code
The GOTO, RETURN, FRETURN, ACCESSORY, EXECUTE, EXIT, BYE,
TERMINAL, CONNECT, and QUIT statements are unconditional
transfers of control. They do not return. When one of
these statements is found OUTSIDE of the domain of an IF,
WHILE, SWITCH, FOR, or DO statement, CACMP expects to find
a label as the next executable statement. If not, CACMP
issues the following semantic warning:
Line 2: WARNING: Cannot reach this statement
N0 = N0+1
^
4. Duplicate labels
CACMP keeps track of label statements. When a label dupli-
cates one previously seen, CACMP issues the warning:
Line 9: WARNING: Duplicate label
label:
^
Note that the label has been truncated to 8 characters.
COM-AND only uses the first 8 characters of a label. Dupli-
cation of the first 8 characters is often the root of a
duplicate label condition.
Version 1.2: 921012
COM-AND Script Utility Page 7
III. CACMP functions (continued)
B. Semantic check (continued)
5. Undefined labels
CACMP also keeps track of label used in GOTO, GOSUB, ON and
WOPEN statements. On completion of processing, any label
referenced by one of these statements but not found in the
script is reported as 'undefined label'. For example:
WARNING: Undefined label: SOMEWHER
6. Label in domain (IF/SWITCH/WHILE/FOR/DO)
Above, it is noted that a GOTO terminates the 'domain' of
an IF, SWITCH, WHILE, FOR, and DO statement. GOTOs may NOT
transfer control INTO the domain of one of these statements.
When a label is encountered within a domain, CACMP reports:
Line 8: WARNING: Label in WHILE domain starting: 3
label:
^
It will be noted (painfully), that a single unclosed domain
(for example, an IF missing its ENDIF) results in MANY
'label in domain' warnings. The clue in this case is that
all errors reference a domain beginning on the same line.
Correct the unclosed domain, and improper 'label in domain'
warnings will disappear.
Version 1.2: 921012
COM-AND Script Utility Page 8
III. CACMP functions (continued)
B. Semantic check (continued)
7. COM-AND stack overflow
COM-AND allows IF, WHILE, SWITCH, FOR and DO statements to
be nested to a depth of 20. When CACMP finds a nesting
level greater than 20 it issues a warning:
WARNING: DO/FOR/IF/SWITCH/WHILE stack overflow
WHILE 1 EQ 1
^
8. COM-AND stack underflow
When an ENDIF, ENDWHILE, ENDSWITCH, ENDFOR or UNTIL statement
is encountered with no corresponding start-of-domain state-
ment, CACMP issues the warning:
WARNING: DO/FOR/IF/SWITCH/WHILE stack underflow
ENDWHILE
^
Version 1.2: 921012
COM-AND Script Utility Page 9
III. CACMP functions (continued)
C. Partial strip
When CACMP is run with the /1 switch, records of the input file
are 'partially stripped' and written to the output file. Partial
stripping is similar in function to the STRIPPER.CMD script once
distributed with COM-AND. Partial stripping consists of:
1) Removal of comment lines
2) Removal of comments on statement lines
3) Removal of all blanks to the left of a statement
4) Reduction of multiple blanks to a single blank
5) Removal of redundant blanks (e.g. " = " -> "=")
The STRIPPER.CMD script only performs function (1) above. Addi-
tionally, CACMP writes the output file records with only a car-
riage return (not carriage return/line feed), as COM-AND needs
only the carriage return.
A file 'partially stripped' by CACMP is smaller than one stripped
by STRIPPER. The actual reduction in size is determined by the
input file, but CACMP necessarily produces a smaller file.
Please note that once stripped by CACMP, a file may not be 'read-
able' by the same editor that produced its source. Some editors
tolerate the missing line feed, and some don't. The popular LIST
program by Vern Buerg, for example, won't display the file
(except as a hex dump).
Lines marked as 'syntax errors' are written to the output file
partially stripped.
Version 1.2: 921012
COM-AND Script Utility Page 10
III. CACMP functions (continued)
D. Full Strip
When CACMP is run with the /s switch, records of the input file
are 'fully stripped' and written to the output file. Full
stripping includes the functions listed above as 'partial
stripping', and:
1) Reduction of label lines to an 8 character maximum
2) Reduction of labels in GOTO, GOSUB, ON and WOPEN
statements to an 8 character maximum
3) Reduction of initial keywords in statements to a four
character maximum.
Again, CACMP writes the output file records with only a carriage
return (not carriage return/line feed) as COM-AND needs only the
carriage return.
A file 'fully stripped' by CACMP is considerably smaller than one
stripped by STRIPPER. The actual reduction in size is determined
by the input file. [Your mileage may vary; contents are shipped
by weight, not volume...]
Lines marked 'syntax errors' are written to the output file, but
only partially stripped.
[Tricky ones in the audience might propose that labels be con-
verted to numeric equivalents. After all, "1:" is a legitimate
label. However, the COM-AND language supports indirect GOTOs.
For example, "GOTO S0" branches to the label in S0 (given that
S0 contains a valid label name). Therefore, such a reduction,
although generally possible, is not supported.]
Version 1.2: 921012
COM-AND Script Utility Page 11
III. CACMP functions (continued)
E. Preprocessing
When CACMP is run with the /P switch, records of the input file
are 'preprocessed' and written to the output file. Preprocessing
performs the full strip as described above, and:
. adds a two byte keyword to each executable line to
speed COM-AND's execution of the statement
Preprocessed scripts are accepted by COM-AND as of its version
2.7. The two-byte code added to each executable line speeds the
interpretor's execution of the statement. [Author's note: the
two byte keyword may easily be recognized - the first byte is
always negative (larger than 127).]
A file 'preprocessed' by CACMP is larger than one stripped by
CACMP. It executes approximately 30% faster than the same script
stripped by CACMP. [Please note, preprocessing does not have any
effect on writes to screen or disc. It simply speeds the
interpretation of script statements.]
Lines marked 'syntax errors' are written to the output file, but
only partially stripped. They are not preprocessed.
Version 1.2: 921012
COM-AND Script Utility Page 12
IV. CACMP and COM-AND
CACMP implements a parser based upon a meta-language specification
of the COM-AND language. COM-AND does not; its interpretor parses
ad hoc (or if you wish, on-the-fly). The advantages of ad hoc
interpretation are:
1) execution speed, and
2) simplicity of extension
The disadvantage of ad hoc interpretation is that a syntax/semantic
utility such as CACMP is not possible (not based on the interpretor's
code, at least).
The important point is that CACMP may kick out perfectly valid
statements because its meta-language statement of the language does
not accommodate a particular construction. COM-AND executes the
statement happily, but CACMP rejects it.
The language syntax implemented is taken from version 2.8 COM-AND
documentation... however, COM-AND proper (not its documentation)
is the final arbiter of syntax (and documentation is adjusted
accordingly <smile>).
If you use this, please save doubtful reports and submit them to
the developer. Such reports are used to further refine CACMP.
For the curious, the meta-language implemented here is similar in
form to the LANGPACK language developed at Bell Labs. LANGPACK per
se was not implemented - a modified Backus-Naur form for the meta-
language was implemented in a lexical compiler created for CACMP.
The parser CACMP implements uses the lexical compiler's output to
control text parsing.
Version 1.2: 921012
COM-AND Script Utility Page 13
V. Program requirements
CACMP is written for an IBM PC or DOS compatible machine. CACMP
uses DOS and BIOS for all I/O... no fancy games with screen
buffers are played.
COM-AND disk I/O is done through the 'Handle' oriented I/O routines
added to DOS 2.0. Therefore DOS 2.0 is a minimum requirement.
CACMP (Version 1.2) requires 110K for itself. You need 256K
to take advantage of it. COM-AND requires 384k to be useful.
Version 1.2: 921012
COM-AND Script Utility Page 14
VI. Author information
CACMP was written using Microsoft Macro-Assembler. The author
likes assembler. Assembly language is an entirely appropriate
vehicle for some of the program, and a not-inappropriate vehicle
for the rest of it. Everything, in moderation...
The author of this program is R. Scott McGinnis of Chicago, IL.
GEnie and Delphi id: TARTAN. CIS id: 73147,2665. Comment and
suggestions (and criticism in moderation) are welcomed:
CABER Software
R. (Scott) McGinnis
P.O. Box 3607 Mdse Mart
Chicago, IL 60654-0607
I thank my wife, Elizabeth, who put up with my obsessing while I
developed the parser on which CACMP is based. The meta-language
specification of a language the size of COM-AND's is an obsessive
task - writing a compiler to compile the meta-language and a parser
to execute the compiler's output... the mind is a terrible thing to
lose. Elizabeth refreshes this one every day.
This program may be distributed freely (but it isn't a whole lot of
use without COM-AND). Any problems that are reported to the author
gets attention.
COM-AND is shareware. If COM-AND is USED after a 30 day period
of evaluation, you MUST pay for it. CACMP is included in the
license to use COM-AND. [Please read REGISTER.DOC.]
Version 1.2: 921012
